<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Advanced &mdash; pymunk 4.0.0 documentation</title>
    
    <link rel="stylesheet" href="_static/pymunk.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '4.0.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="shortcut icon" href="_static/pymunk_favicon.ico"/>
    <link rel="top" title="pymunk 4.0.0 documentation" href="index.html" />
    <link rel="next" title="License" href="license.html" />
    <link rel="prev" title="Slide and Pin Joint Demo Step by Step" href="tutorials/SlideAndPinJoint.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="license.html" title="License"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="tutorials/SlideAndPinJoint.html" title="Slide and Pin Joint Demo Step by Step"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">pymunk 4.0.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="advanced">
<h1>Advanced<a class="headerlink" href="#advanced" title="Permalink to this headline">¶</a></h1>
<p>In this section different &#8220;Advanced&#8221; topics are covered, things you normally
dont need to worry about when you use pymunk but might be of interest if you
want a better understanding of pymunk for example to extend it.</p>
<p>First off, pymunk is a pythonic wrapper around the C-library Chipmunk.</p>
<p>To wrap Chipmunk pymunk uses ctypes. In the bottom an autogenerated layer,
and then a handmade pythonic layer on top to make it nice to use from Python
programs.</p>
<div class="section" id="why-ctypes">
<h2>Why ctypes?<a class="headerlink" href="#why-ctypes" title="Permalink to this headline">¶</a></h2>
<p>The reasons for ctypes instead of [your favorite wrapping solution] can be
summarized as</p>
<ul class="simple">
<li>You only need to write pure python code when wrapping. This is good for
several reasons. I can not really code in c. Sure, I can read it and write
easy things, but Im not a good c coder. What I do know quite well is
python. I imagine that the same is true for most people using pymunk,
after all its a python library. :) Hopefully this means that users of
pymunk can look at how stuff is actually done very easily, and for example
add a missing chipmunk method/property on their own in their own code
without much problem, and without being required to compile/build anything.</li>
<li>ctypes is included in the standard library. Anyone with python has it
already, no dependencies on 3rd party libraries, and some guarantee that it
will stick around for a long time.</li>
<li>The only thing required to run pymunk is python and a c compiler (in those
cases a prebuilt version of chipmunk is not included). This should maximize
the multiplatformness of pymunk, only thing that would even better would
be a pure python library (which might be a bad idea for other reasons,
mainly speed).</li>
<li>Not much magic going on. Working with ctypes is quite straight forward.
Sure, pymunk uses a generator which is a bit of a pain, but at least its
possible to sidestep it if required, which Ive done in some cases. Ive also
got a share amount of problems when stuff didnt work as expected, but I
imagine it would have been even worse with other solutions. At least its
only the c library and python, and not some 3rd party in between.</li>
<li>Non api-breaking fixes in chipmunk doesnt affect pymunk. If a bugfix, some
optimization or whatever is done in chipmunk that doesnt affect the API,
then its enough with a recompile of chipmunk with the new code to benefit
from the fix. Easy for everyone.</li>
<li>Ctypes can run on other python implementations than cpython. Right now pypy
feels the most promising and it is be able to run ctypes just fine.</li>
</ul>
<p>As I see it, the main benefit another solution could give would be speed.
However, there are a couple of arguments why I dont find this as important as
the benefits of ctypes</p>
<ul>
<li><p class="first">You are writing your game in python in the first place, if you really
required top performance than maybe rewrite the whole thing in c would be
better anyway? Or make a optimized binding to chipmunk.</p>
<p>For example, if you really need excellent performance then one possible
optimization would be to write the drawing code in c as well, and have that
interact with chipmunk directly. That way it can be made more performant
than any generic wrapping solution as it would skip the whole layer.</p>
</li>
<li><p class="first">The bottleneck in a full game/application is somewhere else than in the
physics wrapping in many cases. If your game has AI, logic and so on in
python, then the wrapper overhead added by ctypes is not so bad in
comparison.</p>
</li>
<li><p class="first">Pypy. ctypes on pypy has the potential to be very quick. However, right now
with pypy-1.9 the speed of pymunk is actually a bit slower on pypy than on
cpython. Hopefully this will improve in the future.</p>
</li>
</ul>
<p>Note that pymunk has been around since late 2007 which means not all
wrapping options that exist today did exist or was not stable/complete
enough for use by pymunk in the beginning. There are more options available
today, and using ctypes is not set in stone. If a better alternative comes
around then pymunk might switch given the improvements are big enough.</p>
</div>
<div class="section" id="code-layout">
<h2>Code Layout<a class="headerlink" href="#code-layout" title="Permalink to this headline">¶</a></h2>
<p>Most of pymunk should be quite straight forward.</p>
<p>Except for the documented API pymunk has a couple of interesting parts. Low
level bindings to Chipmunk, a custom library load function, a custom
documentation generation extension and a customized setup.py file to allow
compilation of Chipmunk.</p>
<p>The low level chipmunk bindings are located in the two files _chipmunk.py and
_chipmunk_ffi.py. In order to locate and load the compiled chipmunk library
file pymunk uses a custom load_library function in libload.py</p>
<dl class="docutils">
<dt>docs/src/ext/autoexample.py</dt>
<dd>A Sphinx extension that scans a directory and extracts the toplevel
docstring. Used to autogenerate the examples documentation.</dd>
<dt>pymunk/_chipmunk.py</dt>
<dd>This file contains autogenerated low level ctypes binding created by the
generate_bindings script.</dd>
<dt>pymunk/_chipmkunk_ffi.py</dt>
<dd>This file contains manual bindings not automatically generated.</dd>
<dt>pymunk/libload.py</dt>
<dd>This file contains the custom ctypes library load fucntion that is used
by the rest of pymunk to load the Chipmunk library file.</dd>
<dt>setup.py</dt>
<dd>Except for the standard setup stuff this file also contain the custom
build commands to build Chipmunk from source.</dd>
<dt>tests/*</dt>
<dd>Collection of (unit) tests. Does not cover all cases, but most core
things are there. The tests require a working chipmunk library file.</dd>
<dt>tools/*</dt>
<dd>Collection of helper scripts that can be used to various development tasks
such as generating documentation.</dd>
</dl>
</div>
<div class="section" id="tests">
<h2>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h2>
<p>There are a number of unit tests included in the tests folder. Not exactly all
the code is tested, but most of it (at the time of writing its about 85% of
the core parts).</p>
<p>There is a helper script in the tools folder to easily run the tests:</p>
<div class="highlight-python"><pre>&gt; cd tools
&gt; python run_tests.py</pre>
</div>
</div>
<div class="section" id="working-with-non-wrapped-parts-of-chipmunk">
<h2>Working with non-wrapped parts of Chipmunk<a class="headerlink" href="#working-with-non-wrapped-parts-of-chipmunk" title="Permalink to this headline">¶</a></h2>
<p>In case you need to use something that exist in Chipmunk but currently is not
included in pymunk the easiest method is to add it manually. All</p>
<p>Note: If you only want one or two new functions its probably easier to
just add them manually to _chipmunk.py. See the ctypes documentation for
instructions on what the function definitons/structs/whatever should look
like.</p>
<p>For example, lets assume that the is_sleeping property of a body was not
wrapped by pymunk. The Chipmunk method to get this property is named
cpBodyIsSleeping.</p>
<p>First we need some imports:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">ctypes</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">._chipmunk</span> <span class="kn">import</span> <span class="n">cpBody</span><span class="p">,</span> <span class="n">chipmunk_lib</span><span class="p">,</span> <span class="n">function_pointer</span>
</pre></div>
</div>
<p>Then the actual ctypes wrapping:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cpBodyIsSleeping</span> <span class="o">=</span> <span class="p">(</span><span class="n">function_pointer</span><span class="p">(</span><span class="n">cpBool</span><span class="p">,</span> <span class="n">POINTER</span><span class="p">(</span><span class="n">cpBody</span><span class="p">)))</span><span class="o">.</span><span class="n">in_dll</span><span class="p">(</span><span class="n">chipmunk_lib</span><span class="p">,</span> <span class="s">&#39;_cpBodyIsSleeping&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Then to make it easy to use we want to create a python method that looks nice:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">is_sleeping</span><span class="p">(</span><span class="n">body</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">cpffi</span><span class="o">.</span><span class="n">cpBodyIsSleeping</span><span class="p">(</span><span class="n">body</span><span class="o">.</span><span class="n">_body</span><span class="p">)</span>
</pre></div>
</div>
<p>Now we are ready with the mapping and ready to use our new method.</p>
<p>Full example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">ctypes</span> <span class="kn">import</span> <span class="o">*</span>
<span class="kn">from</span> <span class="nn">._chipmunk</span> <span class="kn">import</span> <span class="n">cpBody</span><span class="p">,</span> <span class="n">chipmunk_lib</span><span class="p">,</span> <span class="n">function_pointer</span>

<span class="n">cpBodyIsSleeping</span> <span class="o">=</span> <span class="p">(</span><span class="n">function_pointer</span><span class="p">(</span><span class="n">cpBool</span><span class="p">,</span> <span class="n">POINTER</span><span class="p">(</span><span class="n">cpBody</span><span class="p">)))</span><span class="o">.</span><span class="n">in_dll</span><span class="p">(</span><span class="n">chipmunk_lib</span><span class="p">,</span> <span class="s">&#39;_cpBodyIsSleeping&#39;</span><span class="p">)</span>

<span class="k">def</span> <span class="nf">is_sleeping</span><span class="p">(</span><span class="n">body</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">cpffi</span><span class="o">.</span><span class="n">cpBodyIsSleeping</span><span class="p">(</span><span class="n">body</span><span class="o">.</span><span class="n">_body</span><span class="p">)</span>

<span class="kn">import</span> <span class="nn">pymunk</span>
<span class="n">body</span> <span class="o">=</span> <span class="n">pymunk</span><span class="o">.</span><span class="n">Body</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span>
<span class="k">print</span> <span class="n">is_sleeping</span><span class="p">(</span><span class="n">body</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="regenerate-bindings-to-chipmunk">
<h2>Regenerate bindings to Chipmunk<a class="headerlink" href="#regenerate-bindings-to-chipmunk" title="Permalink to this headline">¶</a></h2>
<p>You need the ctypes code generator. It is part of the ctypeslib package.
You will also need GCC_XML. See the ctypes wiki for instructions
on how to set it up: <a class="reference external" href="http://starship.python.net/crew/theller/wiki/CodeGenerator">http://starship.python.net/crew/theller/wiki/CodeGenerator</a></p>
<p>I have found that ctypeslib and gcc_xml are easiest to get to work under
Linux. Even if you normally work under Windows I suggest you put up a virtual
machine with a linux dist to make things easier.</p>
<p>When ctypeslib (h2xml and xml2py) and gcc_xml are installed you can use
the helper file to regenerate the bindings. It is located in the tools
folder:</p>
<div class="highlight-python"><pre>&gt; cd tools
&gt; python generate_bindings.py</pre>
</div>
<p>You have now created a _chipmunk.py file with generated bindings.
(use &#8211;help to display options, you will most probably want to change the
include path and possibly the lib path)</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/pymunk_logo_sphinx.png" alt="Logo"/>
            </a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="readme.html">Readme</a></li>
<li class="toctree-l1"><a class="reference internal" href="news.html">News</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="pymunk.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Advanced</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#why-ctypes">Why ctypes?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#code-layout">Code Layout</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tests">Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#working-with-non-wrapped-parts-of-chipmunk">Working with non-wrapped parts of Chipmunk</a></li>
<li class="toctree-l2"><a class="reference internal" href="#regenerate-bindings-to-chipmunk">Regenerate bindings to Chipmunk</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference external" href="http://code.google.com/p/pymunk/issues/list">Issue Tracker</a></li>
<li class="toctree-l1"><a class="reference external" href="http://code.google.com/p/pymunk/source/checkout">Source Repository</a></li>
<li class="toctree-l1"><a class="reference external" href="http://code.google.com/p/pymunk/downloads/list">Downloads</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="tutorials/SlideAndPinJoint.html"
                        title="previous chapter">Slide and Pin Joint Demo Step by Step</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="license.html"
                        title="next chapter">License</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/advanced.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="license.html" title="License"
             >next</a> |</li>
        <li class="right" >
          <a href="tutorials/SlideAndPinJoint.html" title="Slide and Pin Joint Demo Step by Step"
             >previous</a> |</li>
        <li><a href="index.html">pymunk 4.0.0 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2013, Victor Blomqvist.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
    </div>
  </body>
</html>